Overview

This PR implements a complete TypeScript client for the OpenHands Agent Server that mirrors the structure and functionality of the Python SDK (software-agent-sdk). The client provides the same classes and parameter names as the Python version for consistency across language implementations.

Key Features

🏗️ Core Architecture

• RemoteConversation: Main conversation management class with full lifecycle support
• RemoteWorkspace: Workspace operations and file management
• RemoteState: Conversation state management and agent execution control
• HttpClient: Robust HTTP client with error handling, retries, and timeout support
• WebSocketClient: Real-time event streaming with automatic reconnection

📡 API Coverage

• Complete implementation based on OpenAPI specification from agent-sdk.json
• All conversation endpoints (create, start, stop, delete, list)
• Workspace file operations (read, write, list, upload, download)
• Event streaming and pagination
• Agent execution control and status monitoring

🔧 Developer Experience

• TypeScript: Full type safety with comprehensive interfaces and enums
• ESLint: Code quality enforcement with TypeScript-specific rules
• Prettier: Consistent code formatting
• Build System: TypeScript compilation with source maps and declaration files
• Examples: Complete usage examples in examples/basic-usage.ts

Implementation Details

Class Structure (Mirrors Python SDK)

// Main conversation management
const conversation = new RemoteConversation(config);
await conversation.start();

// Workspace operations  
const workspace = conversation.workspace;
await workspace.write_file('/path/file.txt', 'content');

// State management
const state = conversation.state;
await state.set_agent_config(agentConfig);

Type Safety

• Comprehensive TypeScript interfaces for all API models
• Enum definitions for status codes, event types, and configuration options
• Generic types for flexible API responses
• Proper error handling with custom exception classes

WebSocket Integration

• Real-time event streaming with automatic reconnection
• Event filtering and callback management
• Proper connection lifecycle management
• Error handling and retry logic

Files Added

Source Code

• src/types/base.ts - Core TypeScript interfaces and enums
• src/client/http-client.ts - HTTP client implementation
• src/events/ - WebSocket client and event management
• src/conversation/ - RemoteConversation and RemoteState classes
• src/workspace/remote-workspace.ts - Workspace operations
• src/models/ - Data models for API requests/responses
• src/index.ts - Public API exports

Configuration

• package.json - Dependencies and build scripts
• tsconfig.json - TypeScript compiler configuration
• .eslintrc.js - ESLint rules and TypeScript integration
• .prettierrc - Code formatting rules
• .gitignore - Git ignore patterns

Documentation & Examples

• README.md - Comprehensive API documentation and usage guide
• examples/basic-usage.ts - Complete usage examples

Testing & Quality

✅ TypeScript Compilation: All code compiles successfully without errors
✅ ESLint Validation: Passes linting with only acceptable warnings for any types
✅ Import/Export: All modules import and export correctly
✅ Build System: Generates proper JavaScript output with type declarations

Usage Example

import { RemoteConversation } from '@openhands/agent-server-typescript-client';

const conversation = new RemoteConversation({
  baseUrl: 'http://localhost:8000',
  apiKey: 'your-api-key'
});

// Start conversation
await conversation.start();

// Send message
await conversation.send_message('Hello, can you help me with a task?');

// Work with files
await conversation.workspace.write_file('/app/config.json', JSON.stringify(config));
const content = await conversation.workspace.read_file('/app/config.json');

// Monitor events
conversation.events.on('message', (event) => {
  console.log('New message:', event.data);
});

Dependencies

Runtime Dependencies

• ws - WebSocket client implementation
• uuid - UUID generation for request tracking

Development Dependencies

• typescript - TypeScript compiler
• @typescript-eslint/* - TypeScript ESLint integration
• eslint - Code linting
• prettier - Code formatting
• jest - Testing framework (configured for future tests)

Future Enhancements

• Add comprehensive unit tests
• Implement request/response interceptors
• Add connection pooling for HTTP client
• Implement caching for workspace operations
• Add metrics and monitoring hooks

Breaking Changes

None - this is a new implementation.

Migration Guide

For users coming from the Python SDK, the API is nearly identical:

# Python SDK
conversation = RemoteConversation(config)
await conversation.start()

// TypeScript Client
const conversation = new RemoteConversation(config);
await conversation.start();

The main differences are TypeScript-specific (type annotations, const vs let, etc.) and JavaScript conventions (camelCase method names in some cases).

@rbren can click here to continue refining the PR